Search for Use Cases topic

This topic describes how Werkbanks search works, advanced search syntax, and how to add custom search entries.

Table of Contents

How Search Works

Werkbank provides a search feature in the navigation panel, helping to find specific Use Cases, Components, or Folders (WerkbankNode's) within your WerkbankRoot. It does more than a simple text search and keeps the familiar tree structure, only hiding nodes that do not match your query. The search is designed to be flexible and extensible.

By default, search is fuzzy and case-insensitive. You can search for:

  • Use Case, Component, or Folder names
  • Tags
  • Descriptions
  • Constraints Preset names
  • Knob Preset names

Adding new searchable fields is straightforward. See Adding Custom Search Entries below.

As your Werkbank grows, finding the right node can become challenging. Werkbank supports advanced search syntax to help you narrow down results:

  • Field-specific search:
    • General: <field>:fuzzy text
    • Example: tag:button
  • Exact search:
    • General: "precise text search"
  • Combine both:
    • General: <field>:"precise text"
    • Example: desc:"hot reload"

Supported Fields

You can target the following fields in your search:

  • name — Use Case, Component, or Folder name
  • tag — Tag
  • desc — Description
  • cPreset — Constraints Preset name
  • kPreset — Knob Preset name

Adding Custom Search Entries

Werkbank’s Addon API lets you extend the search to custom SearchEntries. You can add a SearchCluster with SearchEntries to the UseCaseComposition of any WerkbankNode, making them discoverable via search.

For example, tags are searchable using this implementation:

extension TagsComposerExtension on UseCaseComposer {
  void tags(List<String> tags) {
    // ...
    addSearchCluster(
      SearchCluster(
        semanticDescription: 'Tag',
        field: DescriptionAddon.tagField,
        entries: tags
            .map((tag) => FuzzySearchEntry(
                  searchString: tag,
                  ignoreCase: true,
                ))
            .toList(),
      ),
    );
  }
}

This allows you to call c.tags(['some', 'words']) on UseCaseComposer. Each tag becomes a searchable entry.

Note

All SearchCluster's must be setup during composing the Use Cases. That's why addSearchCluster is called on UseCaseComposer.

Debugging search matches

To better understand why certain use cases are shown or hidden in search, you can enable a debug mode. This is mainly for advanced users fine-tuning their SearchCluster or SearchEntry setup.

Enable debugging by setting the DebugWerkbankFilter in your app, for example in your main():

void main() {
  updateDebugWerkbankFilter(DebugWerkbankFilter.displayAllResults);
  runApp(const YourWerkbank());
}

You can also change the setting at runtime. This will show additional information about why nodes are included or excluded in the search results.